Product Change webhook now includes productRefId for CATALOG_PRODUCT events

^{Minor Upgrade}

The Product Change webhook now includes the productRefId field in CATALOG_PRODUCT events. The productRefId is delivered as part of the webhook payload when product catalog changes occur, so integrators and developers consuming the webhook can access this identifier directly for improved product mapping.

Previously, the CATALOG_PRODUCT payload carried only the legacy numeric application ID and uuid inside content.application. Consumers that needed to call the public Product GraphQL product(id:) query, which expects productRefId, had to make an extra REST GET Product call to translate identifiers. With this update, the additional REST hop is no longer required.

What's new

• A new productRefId field is exposed inside content.application for the ADDED, CHANGED, and REMOVED actions on CATALOG_PRODUCT events.
• When a product does not yet have a productRefId assigned, the field is omitted from the payload rather than sent as null or an empty string.
• STAGING_PRODUCT webhooks, which already exposed productRefId, continue to behave unchanged.

Backward compatibility

This is a fully additive change. The existing id, uuid, and name fields are unchanged, and no field positions shift. Standard JSON deserializers that ignore unknown fields are not impacted.

The following consumer scenarios should be reviewed:

• Strict or closed-schema deserializers (for example, FAIL_ON_UNKNOWN_PROPERTIES = true, or frozen Avro or Protobuf schemas) must allow unknown fields or update their schema to include productRefId.
• Consumers that hash or sign the raw payload string should expect the hash to change, as is the case with any additive payload change.

Feature enablement

No feature enablement is required.

Setting enablement

No setting enablement is required.

Documentation

Developer-facing documentation for the Product Change webhook on developer.appdirect.com is updated to include productRefId in the schema and example payload for CATALOG_PRODUCT events.